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SGMAP PROGRAM 


1.0 SCOPE 

This document contains the description of the SGMAP Program. This program 
produces as output either a numeric dump or a symbolic map from an input 
Landsat Segment Cluster/Classification file or a dic,itized aircraft Ground 
Truth/Processed Ground Truth file. 
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2.0 APPLICABLE DOCUMENTS 


The following documents form a part of this specification: 

AD 63-2457-3308-01 Transferring Badhwar Software. 

AD NAS 9-15200 Technical Memorandum Format Sped <"i cations for LACIE (Phase III) 
and Accuracy Assessment Computer Data Products. 
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3.0 SYSTEM DESCRIPTION 


3.1 SYSTEM FLOWCHART 

The system flowcharts for processing ground truth and cluster/classification 
data files are depicted in Figures 3.1.1 and 3.1.2, respectively. 
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Figure 3.1.1 System Flow for Ground/Processed Ground Truth Input Data F11 
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Figure 3.1.i: System Flow for Cluster/Classification Input Data File 



SGMAP 
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CPTIME 
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Figure 3.1.3 SGMAP Hierarchy 
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3.2 HARDWARE DESCRIPTION 


The software for the SGMAP Program Is operational on the IBM 3031 computer at 
Purdue. 

3.3 SOrniARE DESCRIPTION 

This program produces numeric dumps or symbolic maps of two kinds of files; 
namely, (1) cluster or classification files and f2) ground truth files. 

Cluster or classification files are single channel universal format Image 
files produced by several different clustering and classification programs. 

They are "pixel level" files; 1.e.,they consist of 117 lines with 196 pixels 
per line. (See Section 3.4.1 for a complete file description). 

Ground truth files are single channel universal format Image files that are 
similar to the cluster or classification files except that they are at the 
sub-pixel level, i.e.,they have six sub-pixels corresponding to each pixel on 
a cluster or classification file. They have 351 (3x117) lines with 392 
(2x196) sub-pixels per line. (See Section 3.4.1 for a complete file description). 

If a cluster or classification file is input, then the output numeric flump 
or symbolic map is necessarily at the pixel level also. However if the 
input is a ground truth file, then the output can be either sub-pixel level 
or pixel level. In the latter case the program combines the six sub-oixels 
that correspond to each pixel and determines the label for that pixel by 
majority rule. A numeric dump or symbolic map is then produced of this 
pixel data. ' 

The valid range of sample values is 1-256. 
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3.4 FILE DESCRIPTION 


3.4.1 INPUT DATA FILE 

The two acceptable forms of input data are: 

Cluster or Classification Files: These pixel level files are in universal 

format with one channel per physical record. There are 117 records, each 
having 360 8-bit bytes. 

Ground Truth Files: These sub-pixel level files are in universal format 

with one channel per physical record. There are 351 records, each having 
540 8-bit bytes. The contents of each byte have been biased with -128 and 
are stored in 8-bit two's-complement notation. 
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3.4.2 USER DEFINED FILE (SYMBOL FILE NAME) (SYMBOL FILE TYPE) A 

For output maps, the symbol file defines a corresponding symbol for each of 
the 256 crop code values In the universal format Input file. The user defines 
symbols for each crop code or crop code range; I.e, 1f only one crop code Is 
mapped to a symbol, the beginning and ending of the range are the same. The 
usual procedure followed Is that the user (1) defines all 256 codes to one 
symbol and (2) redefines any codes w‘'1ch merit unique symbols. The last entry 
in the file must be 0 0 0. 


For output numeric dump the only entry is 0 0 N. 


This file provides Inputs In the given formats to the SGMAP program. 

Purpose 


Columns 

1-5 

6-10 

Format 

15 

15 


start 

end 


0 

0 


0 

0 

The following is 

an example 

0 

0 

N 

The following is 

an example 

1 

256 

(blank) 

1 

1 

* 

40 

40 

C 

127 

127 

B 

50 

50 

W 

0 

0 

0 


15 

A1 


symbol 


Defines the start and end of a range 
of sample values assigned to any 
one syn*ol (MAP only) . 

Signifies the end of SYMBOL input 
for a MAP. 

Signifies the end of SYMBOL input 
for a NUMERIC DUMP. 
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3.4.3 USER DEFINED FILE (FILE NA^€) CC A 

This file is used to specify a nuiifcer of parameters mainly related to 
output description. It is composed of card records which are input to the 
SGMAP routine. 


The first six cards have a keyword beginning in column 1 followed by 
parameters in columns 11 through 72. Blanks are optional. The following 
description lists the keywords and describes the corresponding inputs. 


KEYWORD 

ACCEPTABLE INPUTS 

DESCRIPTION 

TYPE 

GROUND TRUTH 

SUB-PIXEL 

CLASS/CLUSTER 

This card defines the type of run. 

In the case where the output 
symbolic map is a classification 
or cluster map, the entry on this 
card is **01 ass /Cl us ter" . In the 
case where the output symbolic map 
is a ground truth map there are two 
possible entries; namely, Cl) "Ground 
Truth" if pixel level output is 
desired and C2)*Sub-P<xel" if 
sub-pixel output is desired. 

OUTPUT 

MAP 

NUMERIC 

This card specifies whether the 
output will be a numeric dump or 
a symbolic map. The corresponding 
entries are "Numeric" and, "Map", 

RECSKP^ 

Positive number 

This card specifies a number of 
records to skip following the header 
record. Normally no skipping is 
required. However, some input files 
do require it. If missing, the 
default is 0. 

DATE^ 

SEGMENT^ 

Free form 

This card gives the date (in free- 
form) for report identification. 

Segment number 

This card specifies the segment 
number for report identification. 

AI^ 

Analyst's name 

This card specifies the analyst's 
name for report identification. 

♦END 

^Op 'onal 

Ignored 

This card identifies the end of the 
user defined cards. 

Input 



3-8 


Next there are one or more cards which specify the part of the image which 
is to be dumped or mapped. Each card specifies the PIXEL (never iub-pixel) 
coordinates of the upper left corner ot the area to be dumped or mapped. 

The output always begins at this corner and produces a display that is 117 
lines by 196 samples. If pixel level output has been specified, these lines 
and samples are pixels; if sub-pixel output has been specified, they are 
sub-pixels. When pixel level output is desired, the vertex 1,1 will cause 
all of the image to be output. However, when sub-pixel output is desired, 
six vertices are required to output the entire image. Of course, fewer 
vertices can be used if only part of the image is desired. The vertices 
(line, sample) are entered one to a card and may begin in any column 1 
through 72./ leading, trailing and embedded blanks on these cards are 
ignored. The range of values permitted is 1 through 79 for lines and 1 
through 99 for samples. A maximum of six vertex cards may be used. 


A SEND card is placed after the last vertex card. 


All cards following the SEND card are considered comments and are printed. 

» 

♦ • 

The following is an example of an user's CC file where the input data is in 
SUB-PIXEL structure. Maps giving complete coverage of all lines and samples 
are desired. 


AI 

.DATE 

SEGf€NT 

TYPE 

OUTPUT 

♦END 

1,1 

40.1 

79.1 
1,99 

40.99 

79.99 
SEND 


MARY ANN TOMPKINS 
DECEMBER 25, 1980 
1981 

SUB-PIXEL 

MAP 
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3.5 SOFTWARE DESCRIPTION 


3.5.1 SGMAP PROGRAM 
Purpose 

SGMAP produces either a numeric dump or a symbolic map from an input Landsat 
Segment Cluster/Classification file or a digitized aircraft Ground 
Truth/Processed Ground Truth file. 

Li nkages 

SGMAP calls CRD2IN, CPTIht, GTMAP, KUSKLA, and SPMAP. 

Interface 
Calling sequence: 

N/A (Adescription for SGMAP EXEC which can be use to load and execute 
SGMAP is found in Section 4.0). 

Calling sequence parameters: 

Input/ 

Argument Output Description 
N/A 

Function value: 

Name Description 
N/A 

Labeled COMMON parameters: 

Full description of labeled COMMON blocks are contained in Appendix A. ' 


Label 

Element 
Variable Position 

Input/ 

Output 

Description 

/MAP/ 

IXLBUF(3060) 1 

0 

Pixel/subpixel input 
buffer. 


IXLINE(98) 2 

0 

Output transformed data 
line. 


IXLTRN(256) 3 

0 

Transformations for a 
sample value. 
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Blank COMMON 

parameters : 


1 Full description of blank COMMON is contained in Appendix A. 

1 

Variable 

Element 

Position 

Input/ 

Output Description 

None 



Inputs 



Uni t 

Type 

Description 

11 

seq. data 

Universal formatted ground truth, classification, 
or cluster file (See section 3.4.1). 

13 

seq. data 

Symbolic maping information (See section' 3.4.2) . 

Outputs 



Unit 

IZ£1 

Description 

6 

Report 

Printout of the user defined control cards. 

14 

Report 

Symbolic map or numeric dump of input data. 


storage requirement 
Not applicable. 

Description 

SGMAP, according to user specification and type of input data file, produces 
symbolic maps or dumps in pixel or subpixel form (See Appendix C). 

FI owchart 
Not applicable. 

Listing 

See Appendix B for program listing. 
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3.5.2 SOFTWARE COMPONENT NO. 1 (CRD2IN) 
Purpose 


Subroutine CRD2IN reads, decodes, and writes to a printer file the user 
supplied card control file. 

Linkages 

CRD2IN is called by S6MAP. 

CRD2IN calls INTPAR and NUf«. 

Interface 
Calling sequence: 

CALL CRD2IN (MTYPE, KOUT, NRECSK, LFTCRS, lERR) . 

Callinr '"“nee parameters: 

I nput/ 

Argument Output 
MTYPE 0 

KOUT 0 

NRECSK 0 

LFTCRS(6) 0 

lERR 0 

Function value: 

N/A. 

Labeled COMMON parameters: 

Full description of labeled COMMON blocks are contained in Appendix A. 
None . 

Blank COMMON parameters: 

* Full description of blank COMMON is contained in Appendix A. 

None. ~ 


Description 

Identifies the type of conversion of 
input structure to output structure. 

Identifies the format of output. 

Number of records to skip. 

Identifies the upper left corner of output. 

Input error indicator flag. 
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Inputs 


Uni t Type 

12 seq. data 

Outputs 

Uni t Type 

6 Printer 

30 

Storage requirement 
Not applicable. 

Description 

CRD2IN reads the key word (first four bytes) on the Control Card and then 
outputs the card. If the key word is not recognized, an error message 
is printed and execution continues. If the key word is recognized, the 
appropriate action regarding the card's parameter is taken. The routine 
determines if all required cards are present and if the parameters are 
acceptable. If either test fails, an error flag is set. 

Flowchart 
Not applicable. 

Listing 

See Appendix B for routine listing. 


Description 

Control card file (See Section 3.4.3). 
Description 

File contains copy of report summary of user 
defined cards. 

Used as a reread file. 
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3.5.3 SOFTWARE COMPONENT NO. 2 (NUFB) 

Purpose 

NUMB decodes character Infornatlon into nuinerical information. 
Linkages 

NUMB is called by CRD2IN. 

Interface 

Calling sequence: 

CALL NU^B (KHAR. NUI^ER, ICOR). 


Calling sequence parameters: 


Argument 

Input/ 

Output 

Description 

KHAR(80) 

I 

Card image. 

NU^BER 

0 

Decoded number. 

I COL 

I 

Column to start decode procedure 

Function value 
Name 

Description 



N/A 

Labeled COMMON parameters: 

Full description of labeled COMMON blocks are contained in Appendix A. 

Element Input/ 

Label Variable Position Output Description 
None 

Blank COMMON parameters: _ 

Full description of bl?nk_COMMON is contained in Appendix A. 

Element Input/ 

Variable Posi tion Output Description 
None 
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Inputs 

None. 


Outputs 

None. 

Storage requirement 
Not applicable. 

Description 

Decodes a number on a user supplied control card starting with the first 
non-blank character in the control card parameter field (ICOL) and ending 
with the first non-blank, non-numeric character. 

Flowchart 
Not applicable. 

Listing 

See Appendix B for routine listing. 
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3.5.4 SOFTWARE COMPONENT NO. 3 (INTPAR) 

Purpose 

Read and decode user defined control cards consisting of a pair of numbers. 


Linkages 

INTPAR is called by CRD2IN. 

Interface 
Calling sequence: 

.. CALL INTPAR (LFTCRS, lERR). 

Calling sequence parameters: 

Input/ 

Argument Output Description 

LFTCRS(6) 0 Identifies upper left corner of output. 

lERR 0 Identifies input error 

lERR = 0 OK 

lERR = 1 Error 

Function value: 

N/A 

Labeled COMMON parameters: 

Full description of labeled COMMON blocks are contained in Appendix A. 
None. 

Blank COMMON parameters: 

Full description of blank COMMON is contained in Appendix A. ~ 
None. ' 

Inputs 

Unit Type Description 

12 Seq. data Control c'»"d file (See Section 3.4.3). 
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Outputs 


Uni t Type 

6 Printer 

30 

Storage requirement 
Not applicable. 

Descri ption 

INTPAR reads and decodes number pairs, input one to a card, separated by 
a coima . 

Flowchart 
Not applicable. 

Listing 

See Appendix B for routine listing. 


Description 

File contains copy of report summary of user 
defined control cards. 

Used as a reread file. 
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3.5.5 SOFWARE COMPONENT NO. 4 (SPMAP) 

Purpose 

SPMAP reads input data in pixel structure and transforms the data into output 
form. 

Linkages 

SPMAP is called by SGMAP. 

Interface 

Cal ling sequence: 

CALL SPMAP (PIXPRO, MOFFS, LINE, LNS). 

Calling sequence parameters: 


Input/ 


Argument 

Output 

[Ascription 

PIXPRO 

0 

Current number of pixels processed. 

MOFFS 

I 

Output pixel offset. 

LINE 

I 

Starting line of pass . 

LNS 

I 

Current line. 

Function value 

: 


N/A. 



Labeled COMMON 

parameters : 



Full description of labeled COMMON blocks are contained in Appendix A. 


Label 

Variable 

Element 

Position 

Input/ 

Output 

Description 

/MAP/ 

IXLBUF(3060) 

1 

0 

Subpixel input buffer. 


IXLINE(98) 

2 

0 

Transformed data line. 


IXLTRN(256) 

3 

I 

Transformations for 
a sample value. 
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Blank COMMON parameters; _ 

Full description of blank COMMON Is contained In Appendix A. 

None. 

Inputs 

Uni t Type Description 

11 Seq. data Universal formatted ground truth file (See 

Section 3.4.1 ) . 

Outputs 

None. 

Storage requiremen t 
Not applicable. 

Descrl ption 

SPMAP reads one line of data Into an Internal buffer beginning with the 
first requested line. Each pixel Is assigned an output symbol by using 
the pixel value to Index Into the pixel transformation buffer which 
contains a user defined symbol. This symbol Is then stored Into an output 
buffer for eventual output. 

Flowchart 
Not applicable. 

Listing 

See Appendix B for routine listing. 
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3.5.6 SOFTWARE COMPONENT NO. 5 (KUSKLA) 
Purpose 


KUSKLA reads input data in pixel structure and transforms the data into 
output form. 

Li nkaqes 

KUSKLA is called by SGMAP. 

Interface 

Calling sequence: 

CALL KUSKLA (MOFFS)'. 

Calling sequence parameters: 

Input/ 

Argument Output Description 
MOFFS I Output pixel offset. 

Function value: 

N/A. 


Labeled COMMON parameters: 

Full description of labeled COMMON blocks are contained in Appendix A. 


Label 

Variable 

El ement 
Position 

Input/ 

Output 

Description 

/MAP/ 

IXLBUF(3060) 

t 

0 

Pixel input buffer. 


IXLINE{98) 

2 

0 

Transformed data line. 


IXLTRN{256) 

3 

I 

Transformations for 

Blank COMMON 

parameters : 



a sample value. 

Full description of blank 

COItiON is 

contained ■ 

In Appendix A. 
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Inputs 


Unit Type Description 

11 Seq. data Universal formated classification or cluster 

file (See Section 3.4.1). 

Outputs 
None . 

Storage requirement 
Not applicable. 

Description 

KUSKLA reads one line of data into an internal buffer, transforms each pixel 
into an output symbol, and stores the pixel into an output buffer for 
eventual output. 

FI owchart 
Not applicable. 

Listing 

See Appendix B for routine listing. 
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3.5.7 SOFTWARE COMPONENT NO. 6 (GTMAP) 

Purpose 

GTMAP reads input data in subpixel structure and converts the data to a 
pixel value. 

Linkages 

GTMAP is called by SGMAP. 

GTMAP calls CROPP. 

Interface 

Calling sequence: 

CALL GTMAP (PIXPRO, MCFFS). 


Calling sequence parameters: 


Argument 

Input/ 

Output 

Description 

PIXPRO 

0 

Current number of pixels processed. 

MOFFS 

I 

Output pixel offset. 

Function value: 



None. 



Labeled COfiMON 

parameters : 



Full description of labeled COMMON blocks are contained in Appendix A. 

Element Input/ 


Label 

Variable 

Position 

Output 

Description v 

/MAP/ 

IXLBUF(3060) 

1 

0 

Subpixel input 
buffer. 


IXLINE(98) 

2 

0 

Output transformed 
data line. 


IXLTRN(256) 

3 

I 

Transformations 
for a sample value. 

/NSBIXL/ 

NSUBPX(6) 

1 


Subpixel that map 
to a pixel . 


Blank COMMON parameters: 

Full description of blank COMMON is contained in Appendix A. 

N/A. 

Inputs 
Uni t 
11 

Outputs 
None. 

Storage requirement 
Not applicable. 

Description 

GTMAP reads three lines of subpixel structure data into an internal buffer. 
The sub-pixels are divided into sub-pixel sets (2 sub-pixel across x 3 lines 
down) and CROPP is called to rule on a pixel value for the set. Each pixel 
is assigned an output symbol by using the pixel value to index into the 
pixel transformation buffer which contains a user defined symbol. This 
symbol is then stored into an output buffer for eventual output. 

FI owchart 
Not applicable. 

Listing 

See Appendix B for routine listing. 


Type Description 

Seq. data Universal formatted ground truth file. 
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3.5.8 SOFTWARE COMPONENT NO. 7 (CROPP) 

Purpose 

CROPP accepts six subpixels as input and outputs a pixel value representative 
of the subpixels. 

Li nkages 

CROPP is called by GRMAP. 

Interface 

Calling sequence: 

CALL CROPP CKROP, IXLCNT) . 


Calling sequence parameters: 


Argumer.t 

Input/ 

Output 

Description 

KROP 

0 

Majority crop code. 

IXLCNT 

0 

Count of number subpixels that match the majority 
code. 

Function value: 
N/A. 



Labeled COMMON 

parameters : 



Full description of labeled COMMON blocks are contained in Appendix A. 


Label 

Variable 

Element 

Position 

Input/ 

Output 

Description 

/NSBIXL/ 

NSUBPX(6) 

1 

I 

Subpixels that map to 





a pixel . 

Blank COMMON 

parameters : 




Full description of blank 

COMMON is contained 

in Appendix A. 


None. 
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Inputs 


/ 


None. 

Ou tputs 

None. 

Storage requirement 
Not applicable. 

De scription 

The first sub-pixel value upon entry ir> considered to be the majority pixel 
(KROP) value. The NSUBPX array is traversed and the number of codes equal 
to KROP counted. This procedure continues until a count of each unique 
code is made. If at anytime a count becomes greater than the count of KROP 
this code becomes KROP's value. 

FI owchart 
Not applicable. 

Listing 

See Appendix B for routine listing. 
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4.0 OPERATION 


4.1 OPERATING INSTRUCTIONS 

SGMAP is operational on the IBM 3031 computer at LARS, West Lafayette, 
Indiana. 

This program requires the use of a D disk which is assigned as a temporary 
disk. This disk will be assigned by the SGMAP EXEC;and the user, therefore, 
should not assign a disk to his machine using a MODE D. 

Prior to invoking the SGMAP EXEC, the user must establish on his A disk a 
SYMBOL file as described in section 3.4.3 and a USER CONTROL file as 
described in section 3.4.4. 

4.2 COMMANDS DESCRIPTION 

To execute SGMAP, the user enters the following series of commands which 
invoke the JOB CONTROL SOFTWARE. 

START 

SGMAP 

END 

The following sections describe each of these commands in detail. Input 
fields are separated by blanks. If more than one word is required to 
describe an input field, the description is enclosed in pointed brackets 
<>. If an input is optional the field is enclosed in square brackets []. 

Do not include these explanatory characters <> [] when actually submitting 
input to the computer. To enter a command, the user types one input per 
defined input field and separates each field with a blank. 
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4.2,1 START 


The START command spools the user's console file. The use of this command 
alone with the END command will provide a listing of all information 
appearing on the user's console file. (If running an interactive job, this 
is the terminal; if running a batch job, this is a system defined device). 

The START command is invoked by the user typing the following: 

START 

4.2.2 SGMAP 

The SGMAP command executes the program. The SGMAP has the following as 
forms and is invoked by typing one of the following, according to the 
users requirement. 

SGMAP <SYf«0L FILE> <SY^B0L fILE> <CC FILE> TAPE# FILE# [TAPE DENSITY] 

< NA^t > < TYPE > < name > 

If the file is on disk - 

SGMAP <SYMB0L FILE> <SYMB0L FILE> <CC“FirE> <F"ILENAME> <FILETYPE> <'FILEMODEr 

< NAME > <_ _TY^ > < NAME > 

The output from the SGMAP program is spooled to the HOUSTON lin*e printer 
The output consists of a MAP and the USER IDENTIFICATION file. 

4.2.3 END 

This command closes the user's console file and causes a copy to be sent to 
the printer. This command has no effect if the START conmand was not 
previously issued. The END command is invoked by the user typing the ' 

following: 

END 
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4.3 OPERATING EXMPLE 


For our example we will assume the following: 

The user's symbol file is established as required on his A disk under the 
file description: 

880 79082 A 

The user's information file is established as required on his A disk under 
the filename of his choice and the required filetype (CC) . (For our example 
we will use SYM880 CC A for our complete file description.) 

The user has a 1600 BPI tape# 2645 which contains the file (17) he wishes to 
map. 


. COMMAND 


EXPLANATION OR ACTION TAKEN 


START 

SGMAP 880 79082 SYM880 2645 17 


END 


Spools the console file. 

Executes the SGMAP PROGRAM 
The user's tape is 1600 BPI; 
therefore, the user inputs 
tape#, fi le#, exercising the 
option of using the defined 
default of 1600 BPI. 

Closes the user's console 
file and spools the file 
to the HOUSTON printer. 
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APPENDIX A 
COMMON BLOCKS 


COMMOH BLOCKS 


COMM0N/MAP/IXLBUF(3O6O),IXLINE(98),rXLTRN(256) 

IXLBUF PIXEL/SUB-PIXEL INPUT BUFFER 

IXLINE OUTPUT TRANSFORMED DATA 

IXLTRN TRANSFORMATIONS FOR SAMPLE VALUE 

C0MM0N/NSBIXL/NSUBPX{6) 

NSUBPX 6 GROUND TRUTH SUB-PIXELS THAT ARE ASSOCIATED WITH 

A CORRESPONDING LACIE PIXEL 
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